/*
 * @brief Common definitions and declarations for the library USB Mass Storage Class driver
 *
 * @note
 * Copyright(C) NXP Semiconductors, 2012
 * Copyright(C) Dean Camera, 2011, 2012
 * All rights reserved.
 *
 * @par
 * Software that is described herein is for illustrative purposes only
 * which provides customers with programming information regarding the
 * LPC products.  This software is supplied "AS IS" without any warranties of
 * any kind, and NXP Semiconductors and its licensor disclaim any and
 * all warranties, express or implied, including all implied warranties of
 * merchantability, fitness for a particular purpose and non-infringement of
 * intellectual property rights.  NXP Semiconductors assumes no responsibility
 * or liability for the use of the software, conveys no license or rights under any
 * patent, copyright, mask work right, or any other intellectual property rights in
 * or to any products. NXP Semiconductors reserves the right to make changes
 * in the software without notification. NXP Semiconductors also makes no
 * representation or warranty that such application will be suitable for the
 * specified use without further testing or modification.
 *
 * @par
 * Permission to use, copy, modify, and distribute this software and its
 * documentation is hereby granted, under NXP Semiconductors' and its
 * licensor's relevant copyrights in the software, without fee, provided that it
 * is used in conjunction with NXP Semiconductors microcontrollers.  This
 * copyright, permission, and disclaimer notice must appear in all copies of
 * this code.
 */

/** @ingroup Group_USBClassMS
 *  @defgroup Group_USBClassMSCommon  Common Class Definitions
 *
 *  @section Sec_ModDescription Module Description
 *  Constants, Types and Enum definitions that are common to both Device and Host modes for the USB
 *  Mass Storage Class.
 *
 *  @{
 */

#ifndef _MS_CLASS_COMMON_H_
#define _MS_CLASS_COMMON_H_

	/* Includes: */
		#include "../../Core/StdDescriptors.h"

	/* Enable C linkage for C++ Compilers: */
		#if defined(__cplusplus)
			extern "C" {
		#endif

	/* Preprocessor Checks: */
		#if !defined(__INCLUDE_FROM_MS_DRIVER)
			#error Do not include this file directly. Include LPCUSBlib/Drivers/USB.h instead.
		#endif

	/* Macros: */
		/** Magic signature for a Command Block Wrapper used in the Mass Storage Bulk-Only transport protocol. */
		#define MS_CBW_SIGNATURE                               0x43425355UL

		/** Magic signature for a Command Status Wrapper used in the Mass Storage Bulk-Only transport protocol. */
		#define MS_CSW_SIGNATURE                               0x53425355UL

		/** Mask for a Command Block Wrapper's flags attribute to specify a command with data sent from host-to-device. */
		#define MS_COMMAND_DIR_DATA_OUT                        (0 << 7)

		/** Mask for a Command Block Wrapper's flags attribute to specify a command with data sent from device-to-host. */
		#define MS_COMMAND_DIR_DATA_IN                         (1 << 7)

		/** @name SCSI Commands*/
		//@{
		/** SCSI Command Code for an INQUIRY command. */
		#define SCSI_CMD_INQUIRY                               0x12

		/** SCSI Command Code for a REQUEST SENSE command. */
		#define SCSI_CMD_REQUEST_SENSE                         0x03

		/** SCSI Command Code for a TEST UNIT READY command. */
		#define SCSI_CMD_TEST_UNIT_READY                       0x00

		/** SCSI Command Code for a READ CAPACITY (10) command. */
		#define SCSI_CMD_READ_CAPACITY_10                      0x25

		/** SCSI Command Code for a SEND DIAGNOSTIC command. */
		#define SCSI_CMD_SEND_DIAGNOSTIC                       0x1D

		/** SCSI Command Code for a PREVENT ALLOW MEDIUM REMOVAL command. */
		#define SCSI_CMD_PREVENT_ALLOW_MEDIUM_REMOVAL          0x1E

		/** SCSI Command Code for a WRITE (10) command. */
		#define SCSI_CMD_WRITE_10                              0x2A

		/** SCSI Command Code for a READ (10) command. */
		#define SCSI_CMD_READ_10                               0x28

		/** SCSI Command Code for a WRITE (6) command. */
		#define SCSI_CMD_WRITE_6                               0x0A

		/** SCSI Command Code for a READ (6) command. */
		#define SCSI_CMD_READ_6                                0x08

		/** SCSI Command Code for a VERIFY (10) command. */
		#define SCSI_CMD_VERIFY_10                             0x2F

		/** SCSI Command Code for a MODE SENSE (6) command. */
		#define SCSI_CMD_MODE_SENSE_6                          0x1A

		/** SCSI Command Code for a MODE SENSE (10) command. */
		#define SCSI_CMD_MODE_SENSE_10                         0x5A
		//@}
		
		/** @name SCSI Sense Key Values */
		//@{
		/** SCSI Sense Code to indicate no error has occurred. */
		#define SCSI_SENSE_KEY_GOOD                            0x00

		/** SCSI Sense Code to indicate that the device has recovered from an error. */
		#define SCSI_SENSE_KEY_RECOVERED_ERROR                 0x01

		/** SCSI Sense Code to indicate that the device is not ready for a new command. */
		#define SCSI_SENSE_KEY_NOT_READY                       0x02

		/** SCSI Sense Code to indicate an error whilst accessing the medium. */
		#define SCSI_SENSE_KEY_MEDIUM_ERROR                    0x03

		/** SCSI Sense Code to indicate a hardware error has occurred. */
		#define SCSI_SENSE_KEY_HARDWARE_ERROR                  0x04

		/** SCSI Sense Code to indicate that an illegal request has been issued. */
		#define SCSI_SENSE_KEY_ILLEGAL_REQUEST                 0x05

		/** SCSI Sense Code to indicate that the unit requires attention from the host to indicate
		 *  a reset event, medium removal or other condition.
		 */
		#define SCSI_SENSE_KEY_UNIT_ATTENTION                  0x06

		/** SCSI Sense Code to indicate that a write attempt on a protected block has been made. */
		#define SCSI_SENSE_KEY_DATA_PROTECT                    0x07

		/** SCSI Sense Code to indicate an error while trying to write to a write-once medium. */
		#define SCSI_SENSE_KEY_BLANK_CHECK                     0x08

		/** SCSI Sense Code to indicate a vendor specific error has occurred. */
		#define SCSI_SENSE_KEY_VENDOR_SPECIFIC                 0x09

		/** SCSI Sense Code to indicate that an EXTENDED COPY command has aborted due to an error. */
		#define SCSI_SENSE_KEY_COPY_ABORTED                    0x0A

		/** SCSI Sense Code to indicate that the device has aborted the issued command. */
		#define SCSI_SENSE_KEY_ABORTED_COMMAND                 0x0B

		/** SCSI Sense Code to indicate an attempt to write past the end of a partition has been made. */
		#define SCSI_SENSE_KEY_VOLUME_OVERFLOW                 0x0D

		/** SCSI Sense Code to indicate that the source data did not match the data read from the medium. */
		#define SCSI_SENSE_KEY_MISCOMPARE                      0x0E
		//@}
		
		/** @name SCSI Additional Sense Codes */
		//@{
		/** SCSI Additional Sense Code to indicate no additional sense information is available. */
		#define SCSI_ASENSE_NO_ADDITIONAL_INFORMATION          0x00

		/** SCSI Additional Sense Code to indicate that the logical unit (LUN) addressed is not ready. */
		#define SCSI_ASENSE_LOGICAL_UNIT_NOT_READY             0x04

		/** SCSI Additional Sense Code to indicate an invalid field was encountered while processing the issued command. */
		#define SCSI_ASENSE_INVALID_FIELD_IN_CDB               0x24

		/** SCSI Additional Sense Code to indicate that a medium that was previously indicated as not ready has now
		 *  become ready for use.
		 */
		#define SCSI_ASENSE_NOT_READY_TO_READY_CHANGE          0x28

		/** SCSI Additional Sense Code to indicate that an attempt to write to a protected area was made. */
		#define SCSI_ASENSE_WRITE_PROTECTED                    0x27

		/** SCSI Additional Sense Code to indicate an error whilst formatting the device medium. */
		#define SCSI_ASENSE_FORMAT_ERROR                       0x31

		/** SCSI Additional Sense Code to indicate an invalid command was issued. */
		#define SCSI_ASENSE_INVALID_COMMAND                    0x20

		/** SCSI Additional Sense Code to indicate a write to a block out outside of the medium's range was issued. */
		#define SCSI_ASENSE_LOGICAL_BLOCK_ADDRESS_OUT_OF_RANGE 0x21

		/** SCSI Additional Sense Code to indicate that no removable medium is inserted into the device. */
		#define SCSI_ASENSE_MEDIUM_NOT_PRESENT                 0x3A
		//@}
		
		/** @name SCSI Additional Sense Key Code Qualifiers */
		//@{
		/** SCSI Additional Sense Qualifier Code to indicate no additional sense qualifier information is available. */
		#define SCSI_ASENSEQ_NO_QUALIFIER                      0x00

		/** SCSI Additional Sense Qualifier Code to indicate that a medium format command failed to complete. */
		#define SCSI_ASENSEQ_FORMAT_COMMAND_FAILED             0x01

		/** SCSI Additional Sense Qualifier Code to indicate that an initializing command must be issued before the issued
		 *  command can be executed.
		 */
		#define SCSI_ASENSEQ_INITIALIZING_COMMAND_REQUIRED     0x02

		/** SCSI Additional Sense Qualifier Code to indicate that an operation is currently in progress. */
		#define SCSI_ASENSEQ_OPERATION_IN_PROGRESS             0x07
		//@}
		
	/* Enums: */
		/** Enum for possible Class, Subclass and Protocol values of device and interface descriptors relating to the Mass
		 *  Storage device class.
		 */
		enum MS_Descriptor_ClassSubclassProtocol_t
		{
			MS_CSCP_MassStorageClass          = 0x08, /**< Descriptor Class value indicating that the device or interface
			                                           *   belongs to the Mass Storage class.
			                                           */
			MS_CSCP_SCSITransparentSubclass   = 0x06, /**< Descriptor Subclass value indicating that the device or interface
			                                           *   belongs to the SCSI Transparent Command Set subclass of the Mass
			                                           *   storage class.
			                                           */
			MS_CSCP_BulkOnlyTransportProtocol = 0x50, /**< Descriptor Protocol value indicating that the device or interface
			                                           *   belongs to the Bulk Only Transport protocol of the Mass Storage class.
			                                           */
		};
	
		/** Enum for the Mass Storage class specific control requests that can be issued by the USB bus host. */
		enum MS_ClassRequests_t
		{
			MS_REQ_GetMaxLUN                  = 0xFE, /**< Mass Storage class-specific request to retrieve the total number of Logical
			                                           *   Units (drives) in the SCSI device.
			                                           */
			MS_REQ_MassStorageReset           = 0xFF, /**< Mass Storage class-specific request to reset the Mass Storage interface,
			                                           *   ready for the next command.
		                                               */
		};

		/** Enum for the possible command status wrapper return status codes. */
		enum MS_CommandStatusCodes_t
		{
			MS_SCSI_COMMAND_Pass              = 0, /**< Command completed with no error */
			MS_SCSI_COMMAND_Fail              = 1, /**< Command failed to complete - host may check the exact error via a
			                                        *   SCSI REQUEST SENSE command.
			                                        */
			MS_SCSI_COMMAND_PhaseError        = 2, /**< Command failed due to being invalid in the current phase. */
		};

	/* Type Defines: */
		/** @brief Mass Storage Class Command Block Wrapper.
		 *
		 *  Type define for a Command Block Wrapper, used in the Mass Storage Bulk-Only Transport protocol.
		 *
		 *  @note Regardless of CPU architecture, these values should be stored as little endian.
		 */
		typedef ATTR_IAR_PACKED struct
		{
			uint32_t Signature; /**< Command block signature, must be @ref MS_CBW_SIGNATURE to indicate a valid Command Block. */
			uint32_t Tag; /**< Unique command ID value, to associate a command block wrapper with its command status wrapper. */
			uint32_t DataTransferLength; /**< Length of the optional data portion of the issued command, in bytes. */
			uint8_t  Flags; /**< Command block flags, indicating command data direction. */
			uint8_t  LUN; /**< Logical Unit number this command is issued to. */
			uint8_t  SCSICommandLength; /**< Length of the issued SCSI command within the SCSI command data array. */
			uint8_t  SCSICommandData[16]; /**< Issued SCSI command in the Command Block. */
		} ATTR_PACKED MS_CommandBlockWrapper_t;

		/** @brief Mass Storage Class Command Status Wrapper.
		 *
		 *  Type define for a Command Status Wrapper, used in the Mass Storage Bulk-Only Transport protocol.
		 *
		 *  @note Regardless of CPU architecture, these values should be stored as little endian.
		 */
		typedef ATTR_IAR_PACKED struct
		{
			uint32_t Signature; /**< Status block signature, must be @ref MS_CSW_SIGNATURE to indicate a valid Command Status. */
			uint32_t Tag; /**< Unique command ID value, to associate a command block wrapper with its command status wrapper. */
			uint32_t DataTransferResidue; /**< Number of bytes of data not processed in the SCSI command. */
			uint8_t  Status; /**< Status code of the issued command - a value from the @ref MS_CommandStatusCodes_t enum. */
		} ATTR_PACKED MS_CommandStatusWrapper_t;

		/** @brief Mass Storage Class SCSI Sense Structure
		 *
		 *  Type define for a SCSI Sense structure. Structures of this type are filled out by the
		 *  device via the @ref MS_Host_RequestSense() function, indicating the current sense data of the
		 *  device (giving explicit error codes for the last issued command). For details of the
		 *  structure contents, refer to the SCSI specifications.
		 */
		typedef ATTR_IAR_PACKED struct
		{
			uint8_t  ResponseCode;

			uint8_t  SegmentNumber;

			unsigned SenseKey            : 4;
			unsigned Reserved            : 1;
			unsigned ILI                 : 1;
			unsigned EOM                 : 1;
			unsigned FileMark            : 1;

			uint8_t  Information[4];
			uint8_t  AdditionalLength;
			uint8_t  CmdSpecificInformation[4];
			uint8_t  AdditionalSenseCode;
			uint8_t  AdditionalSenseQualifier;
			uint8_t  FieldReplaceableUnitCode;
			uint8_t  SenseKeySpecific[3];
		} ATTR_PACKED SCSI_Request_Sense_Response_t;

		/** @brief Mass Storage Class SCSI Inquiry Structure.
		 *
		 *  Type define for a SCSI Inquiry structure. Structures of this type are filled out by the
		 *  device via the @ref MS_Host_GetInquiryData() function, retrieving the attached device's
		 *  information.
		 *
		 *  For details of the structure contents, refer to the SCSI specifications.
		 */
		typedef ATTR_IAR_PACKED struct
		{
			unsigned DeviceType          : 5;
			unsigned PeripheralQualifier : 3;

			unsigned Reserved            : 7;
			unsigned Removable           : 1;

			uint8_t  Version;

			unsigned ResponseDataFormat  : 4;
			unsigned Reserved2           : 1;
			unsigned NormACA             : 1;
			unsigned TrmTsk              : 1;
			unsigned AERC                : 1;

			uint8_t  AdditionalLength;
			uint8_t  Reserved3[2];

			unsigned SoftReset           : 1;
			unsigned CmdQue              : 1;
			unsigned Reserved4           : 1;
			unsigned Linked              : 1;
			unsigned Sync                : 1;
			unsigned WideBus16Bit        : 1;
			unsigned WideBus32Bit        : 1;
			unsigned RelAddr             : 1;

			uint8_t  VendorID[8];
			uint8_t  ProductID[16];
			uint8_t  RevisionID[4];
		} ATTR_PACKED SCSI_Inquiry_Response_t;

	/* Disable C linkage for C++ Compilers: */
		#if defined(__cplusplus)
			}
		#endif

#endif

/** @} */

